--- created: source_filename: /home/runner/work/mknodes/mknodes/mknodes/pages/mkclasspage/__init__.py source_function: MkClassPage.__init__ source_line_no: 46 hide: - toc icon: material/api status: new template: The nodes/Documentation nodes/mkclidoc.html title: MkCliDoc --- [:fa-brands-github: Show source on GitHub](https://github.com/phil65/mknodes/blob/main/mknodes/basenodes/mkclidoc/__init__.py) ### Node for showing documentation for click / typer CLI apps. === "Examples" ### Example: **MkDocs-MkNodes CLI** !!! jinja "Jinja" ``` {.jinja } {{ "mkdocs_mknodes.cli:cli" | MkCliDoc }} ``` !!! python "Python" ``` {.python } MkCliDoc('mkdocs_mknodes.cli:cli') ``` ===! "Rendered" ## MkNodes 🚀🚀🚀 MkNodes CLI interface. Build websites from command line! 🚀🚀🚀 Check out https://phil65.github.io/mkdocs-mknodes/ ! ```` {.python } mknodes [OPTIONS] COMMAND [ARGS]... ```` ### `--install-completion` :mdi-flag: Flag Install completion for the current shell. ### `--show-completion` :mdi-flag: Flag Show completion for the current shell, to copy it or customize the installation. ### `--help` :mdi-flag: Flag Show this message and exit. === "Markdown" ``` {.markdown } ## MkNodes 🚀🚀🚀 MkNodes CLI interface. Build websites from command line! 🚀🚀🚀 Check out https://phil65.github.io/mkdocs-mknodes/ ! ```` {.python } mknodes [OPTIONS] COMMAND [ARGS]... ```` ### `--install-completion` :mdi-flag: Flag Install completion for the current shell. ### `--show-completion` :mdi-flag: Flag Show completion for the current shell, to copy it or customize the installation. ### `--help` :mdi-flag: Flag Show this message and exit. ``` === "Html" ``` {.html }

MkNodes

🚀🚀🚀 MkNodes CLI interface. Build websites from command line! 🚀🚀🚀

Check out https://phil65.github.io/mkdocs-mknodes/ !

mknodes [OPTIONS] COMMAND [ARGS]...
        

--install-completion

Flag Install completion for the current shell.

--show-completion

Flag Show completion for the current shell, to copy it or customize the installation.

--help

Flag Show this message and exit.

``` === "Repr tree" ``` MkCliDoc ╰── MkHeader('`--help`', level=3) ╰── MkMaterialBadge('mdi:flag', 'Flag') ``` ### Example: **SubCommand** !!! jinja "Jinja" ``` {.jinja } {{ "mkdocs_mknodes.cli:cli" | MkCliDoc(prog_name="build") }} ``` !!! python "Python" ``` {.python } MkCliDoc('mkdocs_mknodes.cli:cli', prog_name='build') ``` ===! "Rendered" ## build Create a MkNodes-based website, locally or remotely. Runs the build script on given repository (either locally or a hosted one), adapts the config file automatically and creates the HTML website in given site dir. Further info here: https://phil65.github.io/mkdocs-mknodes/CLI/ ```` {.python } mknodes build [OPTIONS] ```` ### `--repo-url`, `-r` Repository URL of the target package. Can be remote or local. ### `--build-fn`, `-b` Path to the build script. (form: `path.to.module:function` ) ### `--site-dir`, `-d` **Default:** site Path to the folder where the HTML should get written. ### `--clone-depth`, `-c` Git clone depth in case repository is remote. Important for changelog generation. ### `--config-path`, `-p` **Default:** mkdocs.yml Path to the config file. ### `--theme`, `-t` **Default:** material Theme to use for the build. Overrides config setting. ### `--strict`, `-s` :mdi-flag: Flag Strict mode (fails on warnings) ### `-u`, `--use-directory-urls` **Default:** True :mdi-flag: Flag Use directory-style URLs. ### `--verbose`, `-v` :mdi-flag: Flag Enable verbose output. (`DEBUG` level) ### `--quiet`, `-q` :mdi-flag: Flag Suppress output during build. ### `--help` :mdi-flag: Flag Show this message and exit. === "Markdown" ``` {.markdown } ## build Create a MkNodes-based website, locally or remotely. Runs the build script on given repository (either locally or a hosted one), adapts the config file automatically and creates the HTML website in given site dir. Further info here: https://phil65.github.io/mkdocs-mknodes/CLI/ ```` {.python } mknodes build [OPTIONS] ```` ### `--repo-url`, `-r` Repository URL of the target package. Can be remote or local. ### `--build-fn`, `-b` Path to the build script. (form: `path.to.module:function` ) ### `--site-dir`, `-d` **Default:** site Path to the folder where the HTML should get written. ### `--clone-depth`, `-c` Git clone depth in case repository is remote. Important for changelog generation. ### `--config-path`, `-p` **Default:** mkdocs.yml Path to the config file. ### `--theme`, `-t` **Default:** material Theme to use for the build. Overrides config setting. ### `--strict`, `-s` :mdi-flag: Flag Strict mode (fails on warnings) ### `-u`, `--use-directory-urls` **Default:** True :mdi-flag: Flag Use directory-style URLs. ### `--verbose`, `-v` :mdi-flag: Flag Enable verbose output. (`DEBUG` level) ### `--quiet`, `-q` :mdi-flag: Flag Suppress output during build. ### `--help` :mdi-flag: Flag Show this message and exit. ``` === "Html" ``` {.html }

build

Create a MkNodes-based website, locally or remotely.

Runs the build script on given repository (either locally or a hosted one), adapts the config file automatically and creates the HTML website in given site dir.

Further info here: https://phil65.github.io/mkdocs-mknodes/CLI/

mknodes build [OPTIONS]
        

--repo-url, -r

Repository URL of the target package. Can be remote or local.

--build-fn, -b

Path to the build script. (form: path.to.module:function )

--site-dir, -d

Default: site Path to the folder where the HTML should get written.

--clone-depth, -c

Git clone depth in case repository is remote. Important for changelog generation.

--config-path, -p

Default: mkdocs.yml Path to the config file.

--theme, -t

Default: material Theme to use for the build. Overrides config setting.

--strict, -s

Flag Strict mode (fails on warnings)

-u, --use-directory-urls

Default: True Flag Use directory-style URLs.

--verbose, -v

Flag Enable verbose output. (DEBUG level)

--quiet, -q

Flag Suppress output during build.

--help

Flag Show this message and exit.

``` === "Repr tree" ``` MkCliDoc ╰── MkHeader('`--help`', level=3) ╰── MkMaterialBadge('mdi:flag', 'Flag') ``` === "DocStrings" ::: mknodes.MkCliDoc options: show_docstring_description: False === "Base classes" | Name | Children | Inherits | |--- | --- | --- | | **[MkTemplate](https://phil65.github.io/mknodes/)**
*mknodes.templatenodes.mktemplate*
Node representing a jinja template\. | | | === "â‹” Inheritance diagram" ``` mermaid graph TD 94721308870576["mkclidoc.MkCliDoc"] 94721308869584["mktemplate.MkTemplate"] 94721311697232["mkcontainer.MkContainer"] 94721308848336["mknode.MkNode"] 94721311766592["node.Node"] 140564252373184["builtins.object"] 94721308869584 --> 94721308870576 94721311697232 --> 94721308869584 94721308848336 --> 94721311697232 94721311766592 --> 94721308848336 140564252373184 --> 94721311766592 ``` === "NodeFile" ``` {.toml title='/home/runner/work/mknodes/mknodes/mknodes/basenodes/mkclidoc/metadata.toml'} [metadata] icon = "mdi:api" name = "MkCliDoc" [examples.cli] title = "MkDocs-MkNodes CLI" jinja = """ {{ "mkdocs_mknodes.cli:cli" | MkCliDoc }} """ [examples.sub_command] title = "SubCommand" jinja = """ {{ "mkdocs_mknodes.cli:cli" | MkCliDoc(prog_name="build") }} """ [examples.argparse] title = "ArgumentParser" python = """ from git_changelog import cli import mknodes as mk parser = cli.get_parser() mk.MkCliDoc(parser) """ [fragments] param_template = """ {{ param.opt_str | MkHeader(level=3) }} {% if param.required %} "{{ "REQUIRED" | md_style(bold=True) }}" {% endif %} {% if param.envvar %} Environment variable{{ param.envvar }} {% endif %} {% if param.multiple %} {{ "Multiple values allowed." | md_style(bold=True) }} {% endif %} {% if param.default %} {{ "Default:" | md_style(bold=True) }} {{ param.default }} {% endif %} {% if param.is_flag %} {{ "mdi:flag" | MkMaterialBadge("Flag") }} {% endif %} {% if param.help %} {{ param.help }} {% endif %} """ command_template = """ {{ info.name | MkHeader }} {{ info.description }} {{ info.usage | MkCode }} {% for param in info.params %} {{ "fragments/param_template" | render_template(param=param) }} {% endfor %} """ [output.markdown] template = """ {% if node.info %} {{ "fragments/command_template" | render_template(info=node.info) }} {% if node.show_subcommands %} {% for sub_info in node.info.subcommands.values() %} {{ "fragments/command_template" | render_template(info=sub_info) }} {% endfor %} {% endif %} {% endif %} """ ``` === "Code" ``` {.python title='mknodes.basenodes.mkclidoc.MkCliDoc' linenums='16'} class MkCliDoc(mktemplate.MkTemplate): """Node for showing documentation for click / typer CLI apps.""" ICON = "material/api" def __init__( self, target: str | argparse.ArgumentParser | None = None, *, prog_name: str | None = None, show_hidden: bool = False, show_subcommands: bool = False, **kwargs: Any, ): r"""Constructor. Args: target: Dotted path to click group / typer instance / ArgumentParser prog_name: Program name show_hidden: Show commands and options that are marked as hidden. show_subcommands: List subcommands of a given command. kwargs: Keyword arguments passed to parent """ super().__init__("output/markdown/template", **kwargs) self.target = target self.prog_name = prog_name self.show_hidden = show_hidden self.show_subcommands = show_subcommands @property def info(self) -> clinspector.CommandInfo | None: import importlib match self.target: case str(): module, command = self.target.split(":") prog_name = self.prog_name mod = importlib.import_module(module) instance = getattr(mod, command) case None: if cli_eps := self.ctx.metadata.entry_points.get_group("console_scripts"): module, command = cli_eps[0].value.split(":") prog_name = cli_eps[0].name mod = importlib.import_module(module) instance = getattr(mod, command) else: return None case _: instance = self.target prog_name = self.prog_name return clinspector.get_cmd_info(instance, command=prog_name) ```